javadoc - Java API ドキュメントジェネレータ

Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、Sun Solaris を使用した場合のものです。

目次

リファレンスガイド

実行

リファレンスガイド

形式

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

引数を指定する順序は任意です。Javadoc ツールでの、処理対象の .java ファイルを決定する方法の詳細については、「ソースファイルの処理」を参照してください。

options
このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。
packagenames
スペースで区切られた一連のパッケージ名です。 たとえば、java.lang java.lang.reflect java.awt のように指定します。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用不可です。 再帰的処理のためには、-subpackages を使用します。Javadoc ツールは、-sourcepath を使ってこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。
sourcefilenames
スペースで区切られた一連のソースファイル名です。各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。 Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (「Identifiers」を参照)。したがって、ハイフンを含む名前 (X-Buffer など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。 ソースファイル名の前に指定したパスによって、javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときに -sourcepath は使いません。相対パスは、現在のディレクトリからの相対パスです。 Button.java を渡すことは、./Button.java を渡すことと同じです。ソースファイル名をフルパスで指定すると、/home/src/java/awt/Graphics*.java のようになります。「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイル名を混在させることもできます。
-subpackages pkg1:pkg2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソースファイル名を指定する必要はありません。
@argfiles
Javadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。このファイルの中では、ワイルドカード (*) および -J オプションは指定できません。

説明

Javadoc ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。

Javadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。javadoc ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために -subpackages を使用するか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (.java) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。

ソースファイルの処理

Javadoc ツールは、末尾に .java の付いたファイル以外に、ソースファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの .java ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。 パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2) -subpackages を使用する、(3) ソースファイル名にワイルドカードを使用する (*.java) という方法です。これらの方法を使用する場合、Javadoc ツールは、.java ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。

リンクの処理 - Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、自動的に相互参照リンクを追加します。このようなリンクは、次のような場所に追加されます。

コマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、-link および -linkoffline オプションを利用できます。

その他の処理についての詳細 - Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。 ドキュメントを追加生成することはできません。 つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。

実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは javac の一部を呼び出すことにより、宣言をコンパイルし、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。

Javadoc ツールは、メソッド本体のない純粋なスタブファイルである .java ソースファイルに対しても、実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。

コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。 実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、.class ファイル内に存在するが、ソースコード内には存在しないデフォルトコンストラクタ (Java 言語仕様のセクション 8.6.7) をドキュメント化します。

通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。

Javadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、「クラスの検索方法」を参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。

Javadoc のドックレット

Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。 標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。

-doclet コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。

関連ドキュメントおよびドックレット

用語

「ドキュメンテーションコメント」、「doc コメント」、「主説明」、「タグ」、「ブロックタグ」、および「インラインタグ」の用語については、「ドキュメンテーションコメント」で説明します。次のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。

生成ドキュメント (generated document)
javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。

名前 (name)
Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、java.lang.String.equals(java.lang.Object) のように完全修飾することも、equals(Object) のように部分修飾することもできます。

ドキュメント化されるクラス (documented classes)
javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。

包含クラス (included classes)
ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」 と同じ。

除外クラス (excluded classes)
ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。

参照クラス (referenced classes)
ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は 1.3 から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。

外部参照クラス (external referenced classes)
参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、java.awt パッケージに対してだけ Javadoc ツールを実行した場合、Object などの java.lang 内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、-link および -linkoffline オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。

ソースファイル

Javadoc ツールは、4 種類の異なるソースファイルから出力結果を生成します。そのファイルは、クラスの Java 言語ソースファイル (.java)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートファイルについても説明します。

クラスソースコードファイル

それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーションコメントを持つことができ、それを .java ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。

パッケージコメントファイル

それぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。 その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。

パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。

各パッケージは、単一の package.html ファイル、単一の package-info.java ファイルのいずれかを持つことができますが、両方を持つことはできません。このどちらかのファイルを .java ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。

package-info.java - このファイルには、次の構造のパッケージコメントを格納できます。 コメントはパッケージ宣言の前に配置します。

File:java/applet/package-info.java

/**
 * Provides the classes necessary to create an  
 * applet and the classes an applet uses 
 * to communicate with its applet context.
 * <p>
 * The applet framework involves two entities:
 * the applet and the applet context.
 * An applet is an embeddable window (see the
 * {@link java.awt.Panel} class) with a few extra
 * methods that the applet context can use to 
 * initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

コメント区切り文字の /** と /* は記述する必要がありますが、中間行の行頭のアスタリスクは省略してもかまいません。

package.html - このファイルには、次の構造のパッケージコメントを格納できます。 コメントは <body> 要素内に配置します。

File:java/applet/package.html

<HTML>
<BODY>
Provides the classes necessary to create an applet and the 
classes an applet uses to communicate with its applet context.
<p>
The applet framework involves two entities: the applet
and the applet context. An applet is an embeddable
window (see the {@link java.awt.Panel} class) with a
few extra methods that the applet context can use to
initialize, start, and stop the applet. 

@since 1.0 
@see java.awt
</BODY>
</HTML>

これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述されています。それは、このドキュメンテーションコメントには、コメント区切り文字である /** と */、および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、<body> と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、すべてのブロックタグは、主説明のあとに置かなければなりません。パッケージコメントファイルに @see タグを追加する場合は、完全指定の名前を使用する必要があります。詳細は、 package.html の例を参照してください。

パッケージコメントファイルの処理 - Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。

概要コメントファイル

ドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。 その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージセット全体に当てはまるドキュメントを記述します。

概要コメントファイルを作成する場合は、ファイルに任意の名前を付け、任意の場所に置くことができます。ただし、通常は、ファイル名を overview.html にして、ソースツリーの最上位レベルに置きます。たとえば、java.applet パッケージのソースファイルが /home/user/src/java/applet ディレクトリに含まれている場合は、/home/user/src/overview.html に概要コメントファイルを作成できます。

異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、内部ドキュメンテーション用に -private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。

概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、<body> と最初の文の間にタイトルその他のテキストを含めないようにします。概要タグを含めることができます。 どのドキュメンテーションコメントについても、インラインタグ ({@link} など) 以外のすべてのタグは、主説明のあとに置く必要があります。@see タグを追加する場合は、完全指定の名前を使用しなければなりません。

Javadoc ツールの実行時に、-overview オプションを使って概要コメントファイル名を指定します。このファイルは、パッケージコメントファイルと同じように処理されます。

その他の未処理のファイル

ソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。

未処理のファイルをソースに含めるには、それらのファイルを doc-files というディレクトリに置きます。 このディレクトリは、ソースファイルがある任意のパッケージディレクトリの下に作成できます。このようなサブディレクトリは、パッケージごとに 1 つ用意できます。イメージ、サンプルコード、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンのイメージ button.gif を java.awt.Button クラスのドキュメントに含める場合は、そのファイルを /home/user/src/java/awt/doc-files/ ディレクトリに置きます。doc-files ディレクトリを /home/user/src/java/doc-files に置くことはできません。 これは、java はパッケージではなく、そのディレクトリそのものにソースファイルが入っていないからです。

これらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。 これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、Button.java のドキュメンテーションコメント内のリンクは、次のようになります。

    /**
     * This button looks like this: 
     * <img src="doc-files/Button.gif">
     */

テストファイルおよびテンプレートファイル

一部の開発者から、テストファイルおよびテンプレートファイルを対応するソースファイルの近くのソースツリーに保存したいという要望がありました。つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに保存したいということです。

個別のソースファイル名で明示的に渡して Javadoc ツールを実行する場合は、テストファイルおよびテンプレートファイルを意図的に除外して、処理されないようにすることができます。ただし、パッケージ名またはワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイルおよびテンプレートファイルが処理されないようにする必要があります。

テストファイルとテンプレートファイルの違いは、テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、テンプレートファイルは、そうではないという点です。 ただし、テンプレートファイルも「.java」で終わることができます。

テストファイル - 開発者の多くは、あるパッケージのコンパイル可能で実行可能なテストファイルをそのパッケージのソースファイルと同じディレクトリに配置したいと考えています。しかしテストファイルは、名前なしパッケージなど、ソースファイルパッケージとは別のパッケージに属させたいとも考えています (そのため、テストファイルには package ステートメントがないか、またはソースとは別の package ステートメントがある)。このような状況では、コマンド行で指定されているソースのパッケージ名を指定してそのソースがドキュメント化されているときに、テストファイルは警告またはエラーを引き起こします。そのようなテストファイルはサブディレクトリに配置する必要があります。com.package1 に追加する場合は、それらのテストファイルを、ハイフンが含まれるためパッケージ名としては無効になるサブディレクトリに配置します。

    com/package1/test-files/

こうすると、Javadoc ツールでは警告なしで test ディレクトリをスキップします。

テストファイルに doc コメントが含まれる場合、次のようにワイルドカードを含んだテストソースファイル名で渡してテストファイルのドキュメントを生成するように、Javadoc ツールを別個に実行できるように設定できます。 たとえば、com/package1/test-files/*.java などです。

ソースファイルのテンプレート - テンプレートファイルの名前は「.java」で終わることもありますが、テンプレートファイルはコンパイルできません。ソースディレクトリに保持したいソースファイルのテンプレートがある場合は、このファイル名にハイフン (Buffer-Template.java など) やその他の不正な Java 文字を使用します。 こうすることで、処理されないようになります。これは、Javadoc ツールが処理するのは、「.java」接尾辞を除いた名前が 正規のクラス名であるソースファイルだけであるためです (「識別子」参照)。

生成されるファイル

デフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。 それぞれの HTML ページは、個々のファイルに相当します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (package-summary.html など) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。

基本内容ページ

相互参照ページ

サポートファイル

HTML フレーム

Javadoc ツールは、下の図に示すように、2 〜 3 つの HTML フレームを生成します。1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。単一のパッケージに属するソースファイル (*.java) または単一のパッケージ名を引数として javadoc コマンドに渡す場合は、左側の列にクラスの一覧を表示するフレーム (C) 1 つだけが作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、overview-summary.html です。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。[フレームなし] リンクをクリックするか、overview-summary.html を最初に表示すると、フレームを省略できます。

HTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してください。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレームをスクロールしたり、[印刷] メニューコマンドを使ってそのフレームを印刷したりできます。

              ------------                  ------------
              |C| Detail |                  |P| Detail |
              | |        |                  | |        |
              | |        |                  |-|        |
              | |        |                  |C|        |
              | |        |                  | |        |
              | |        |                  | |        |
              ------------                  ------------
             javadoc *.java           javadoc java.lang java.awt

HTML フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。

生成されるファイルの構造

生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。

たとえば、java.applet.Applet クラスに対して生成されるドキュメントは、java/applet/Applet.html に格納されます。生成先のディレクトリの名前が apidocs だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。

注 - 下の階層図で、ディレクトリは太字 (bold) で示してあります。アスタリスク (*) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合は、package-list は作成されますが、内容は空です。doc-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。


apidocs                             最上位ディレクトリ
   index.html                       HTML フレームを設定する初期ページ
 * overview-summary.html            全パッケージのリスト。 先頭に要約文がある
   overview-tree.html               全パッケージのクラス階層のリスト
   deprecated-list.html             全パッケージの推奨されない API のリスト
   constant-values.html             全パッケージの static フィールドの値のリスト
   serialized-form.html             全パッケージの直列化された形式のリスト
 * overview-frame.html              全パッケージのリスト。 左上のフレームに表示される
   allclasses-frame.html            全パッケージの全クラスのリスト。 左下のフレームに表示される
   help-doc.html                    これらのページの構成を示すユーザーヘルプを表示する
   index-all.html                   -splitindex オプションなしで作成されたデフォルト索引
   index-files                      -splitindex オプションを指定して作成されたディレクトリ
       index-<number>.html          -splitindex オプションを指定して作成された索引ファイル
   package-list                     パッケージ名のリスト。 外部参照を解決するためだけに使用される
   stylesheet.css                   フォント、色、配置を定義する HTML スタイルシート
   java                             パッケージディレクトリ
       applet                       サブパッケージディレクトリ
            Applet.html             Applet クラスのページ
            AppletContext.html      AppletContext インタフェースのページ
            AppletStub.html         AppletStub インタフェースのページ
            AudioClip.html          AudioClip インタフェースのページ
          * package-summary.html    このパッケージのクラスのリスト。 先頭に要約文がある
          * package-frame.html      このパッケージのクラスのリスト。 左下のフレームに表示される
          * package-tree.html       このパッケージのクラス階層のリスト
            package-use             このパッケージが使用されている場所のリスト
            doc-files               イメージやサンプルのファイルが格納されるディレクトリ
            class-use               API が使用されている場所のページを格納するディレクトリ
                Applet.html         Applet クラスを使用するページ
                AppletContext.html  AppletContext インタフェースを使用するページ
                AppletStub.html     AppletStub インタフェースを使用するページ
                AudioClip.html      AudioClip インタフェースを使用するページ
   src-html                         ソースコードディレクトリ
       java                         パッケージディレクトリ
           applet                   サブパッケージディレクトリ
                Applet.html         Applet ソースコードのページ
                AppletContext.html  AppletContext ソースコードのページ
                AppletStub.html     AppletStub ソースコードのページ
                AudioClip.html      AudioClip ソースコードのページ

生成される API 宣言

Javadoc ツールは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、その API 用の宣言を生成します。 この宣言は、その API 項目の宣言です。たとえば、Boolean クラスの宣言は、次のようになります。

public final class Boolean
extends Object
implements Serializable

また、Boolean.valueOf メソッドの宣言は、次のようになります。

public static Boolean valueOf(String s)

Javadoc ツールは、修飾子 public、protected、private、abstract、final、static、transient、および volatile を組み込むことができますが、synchronized と native を組み込むことができません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。

API では、並行性のセマンティクスについて、キーワード synchronized に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。 たとえば、「1 つの Enumeration を複数のスレッドから並行して使用することはできない」などのコメントを記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述するべきではありません。たとえば、Hashtable はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありません。バケットレベルで内部的に同期化する権利を残しておく必要があります。 そうすれば、より高度な並行性が提供されます。

ドキュメンテーションコメント

オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。

ソースコードへのコメントの挿入

ソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント ("doc comments") を記述することができます。各パッケージにドキュメンテーションコメントを作成できます。 構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」と呼ばれています (この用語は商標関連の使用法に違反)。ドキュメンテーションコメントは、コメントの始まりを示す文字列 /** と、コメントの終わりを示す文字列 */ の間にある文字で構成されます。行の先頭のアスタリスクは、各行に記述できます。 詳細は、以下で説明します。コメントのテキストは、複数行にわたって記述できます。 

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */

次のようにして 1 行に記述すると、スペースを節約できます。

/** This comment takes up only one line. */

コメントの配置 - ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。 クラスの例、メソッドの例、およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーションコメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。

よくある間違いは、クラスのコメントとクラスの宣言の間に import 文を置いてしまうことです。このような記述はしないでください。 このようなクラスコメントは無視されます。

   /**
    * This is the class comment for the class Whatever.
    */

    import com.sun;   // MISTAKE - Important not to put import statement here

    public class Whatever {
    }

ドキュメンテーションコメントは主説明のあとにタグセクションが続く - コメントの開始区切り文字である /** のあとからタグセクションまでが主説明になります。タグセクションは、先頭文字が @ である行で定義される最初のブロックタグから始まります (行の先頭のアスタリスク、空白、および行の先頭の区切り文字 /** は除く)。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。 何回も記述できるタグと、1 回しか記述できないタグがあります。例えば、次の @see からタグセクションが始まります。

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

ブロックタグとインラインタグ - 「タグ」は、Javadoc が処理できる、ドキュメンテーションコメント内の特別なキーワードです。@tag のように記述するブロックタグ (「スタンドアロンタグ」とも呼ばれる) と、インラインタグ ({@tag} のように中括弧で囲んで記述) の 2 種類のタグがあります。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (/**) を除いて、行の先頭に置かなければなりません。これは、テキスト内のそれ以外の位置で @ 文字を使用しても、タグの開始としては解釈されないことを意味しています。行の最初に @ 文字を使用してもタグとして解釈されないようにするには、HTML エンティティーの「@」を使用してください。それぞれのブロックタグには、対応付けられたテキストがあります。 このテキストは、タグのあとから、次のタグの前、またはドキュメンテーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈されます。次のコード例には、ブロックタグ @deprecated と、インラインタグ {@link} が含まれています。 

/**
 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

コメントは HTML で記述する - テキストは HTML 形式で記述しなければなりません。 これは、HTML のエンティティーを使う必要があること、および HTML タグを使用できることを意味します。記述する HTML のバージョンとしては、使用するブラウザがサポートする任意のバージョンを使用できます。 標準ドックレットは、カスケーディングスタイルシート (CSS) とフレームを含め、すべての部分 (ドキュメンテーションコメント以外の部分) で HTML 3.2 に準拠したコードを生成するように作成されています。ただし、フレームセット対応のため、生成される各ファイルには「HTML 4.0」と記述されます。

たとえば、より小さい (<) およびより大きい (>) という記号は< および > として記述する必要があります。同様に、アンパサンド (&) は、& と記述する必要があります。次の例では、ボールドの HTML タグ <b> を使っています。

次に、ドキュメンテーションコメントを示します。

/**
 * This is a <b>doc</b> comment.
 * @see java.lang.Object
 */

行頭のアスタリスク - Javadoc は、ドキュメンテーションコメントを解析するときに、各行の先頭にあるアスタリスク (*) をすべて破棄します。 また、最初のアスタリスク (*) より前の空白とタブも破棄します。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの <PRE> タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントは区切り文字 /** または <PRE> タグよりも左寄りになります。

最初の文 - 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティーに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバーの概要の部分にコピーされます。

複数フィールドの宣言 - Java では、1 つの文で複数のフィールドを宣言できます。 ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。 そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュメンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述すると不適切です。 この場合は、宣言を 2 つに分けることをお勧めします。

/** 
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // Avoid this

上記のコードからは、次のようなドキュメントが生成されます。

public int x
The horizontal and vertical distances of point (x,y)
public int y
The horizontal and vertical distances of point (x,y)

見出しタグはなるべく使用しない - メンバーに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。 Javadoc ツールは、完全に構造化されたドキュメントを作成するので、このような構造化タグが使われていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しタグを使って独自の構造を組み立ててかまいません。

メソッドコメントの自動コピー

Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。

ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが -sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスがドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。

クラスおよびインタフェースからの継承 - クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。

最初の 2 つのケース (メソッドがオーバーライドしている場合) では、Javadoc ツールは、そのコメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成し、オーバーライドされているメソッドへのリンクを書き込みます。

3 つ目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、javadoc ツールは、オーバーライドしているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメントが継承されているかどうかにかかわりません。

メソッドの説明が継承されるアルゴリズム - あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。 このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できるように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。

  1. 直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する
  2. 手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
  3. 手順 2 でドキュメンテーションコメントが見つからなかった場合で、このクラスが Object 以外のクラスである (インタフェースではない) 場合は、次のように処理する
    1. スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する
    2. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する

javadoc タグ

Javadoc ツールは、Java のドキュメンテーションコメント内に埋め込まれた特別なタグを解析します。これらのドキュメンテーションタグを使うと、書式の整った完全な API ドキュメントをソースコードから自動的に生成できます。タグは、単価記号 (@) で始まり、大文字と小文字が区別されます。 これらのタグは、定められたとおりの大文字と小文字を使用して記述する必要があります。タグは、行の先頭 (先行する空白と省略可能なアスタリスクは除く) に置かなければなりません。慣例として、同じ名前のタグは 1 か所にまとめて記述するようにします。たとえば、@see タグが複数ある場合は、すべてを 1 か所にまとめて記述します。

タグには 2 つのタイプがあります。

今後のリリースで導入されるタグについては、「Proposed Javadoc Tags」を参照してください。

現時点で有効なタグは、次のとおりです。

タグ 導入された JDK/SDK のバージョン
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0

カスタムタグについては、-tag オプションを参照してください。

@author  name-text
-author オプションが使われている場合、生成ドキュメントに「著者」の項目を追加し、指定された name-text を書き込みます。1 つのドキュメンテーションコメントに複数の @author タグを含めることができます。1 つの @author タグに 1 つの名前を指定することも、1 つのタグに複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。

詳細については、「タグを使用できる場所」および @author タグのドキュメントを参照してください。

@deprecated  deprecated-text

注: JDK 5.0 から、@Deprecated 注釈を使って特定のプログラム要素を非推奨にできるようになりました。

この API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、deprecated-text を主説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。

deprecated-text の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。また、代わりの API を指し示す {@link} タグ (Javadoc 1.2 以降の場合) を含める必要があります。 次のように記述します。

詳細については、@deprecated タグのドキュメントを参照してください。

/**
 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

推奨されないタグについての詳細は、@deprecated タグのドキュメントを参照してください。

{@code  text}
<code>{@literal}</code> と同等です。

テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、text を code フォントで表示します。これにより doc コメントでは、パラメータの種類 (<Object>)、不等号 (3 < 4)、または矢印 (<-) などで、HTML エンティティー (< および >) ではなく、通常の山括弧 (< および >) を使用できます。たとえば doc コメントのテキスト

     {@code A<B>C}

は、生成された HTML ページで、次のようにそのまま表示されます。 

     A<B>C

注目すべき点として、<B> は太字であると解釈されませんが、コードフォントになります。

コードフォントなしで同じ機能を実現するには、{@literal} を使用します。

{@docRoot}
生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの下部から著作権のページにリンクします。

この {@docRoot} タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。

  1. コマンド行では、ヘッダー、フッター、またはボトムノートは次のように定義します。 
       javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'

    - {@docRoot} をこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、「{{@docRoot}}」のように、中括弧を二重にする必要があります。さらに、-bottom などのオプションに対する引数を、単一引用符ではなく、二重引用符で囲む必要があります。 href 引数の値を囲む引用符は省略します。

  2. ドキュメンテーションコメントの中では、次のように使用します。 
       /**
    * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
    */

このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。次に例を示します。 

  <a href="{@docRoot}/copyright.html">

次のように解決されます。 

  <a href="../../copyright.html">      java/lang/Object.java の場合

および 

  <a href="../../../copyright.html">   java/lang/ref/Reference.java の場合

@exception  class-name  description
@exception タグは、@throws タグと同義です。

{@inheritDoc} 
もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーションコメントに、ドキュメントを継承 (コピー) します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。

このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。

継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。

{@link   package.class#member   label} 
表示テキスト label とのインラインリンクを挿入します。 label は、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。

このタグは、@see タグとよく似ています。 どちらのタグも、package.class#member および label の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、{@link} は、リンクを [関連項目] セクションに置くのではなく、インラインリンクを生成するということです。また、インラインテキストのほかの部分と区別するために、{@link} タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティーの「}」を使います。

1 つの文の中で使用できる {@link} タグの数に制限はありません。このタグは、ドキュメンテーションコメントの主説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。

たとえば、次のコメントでは getComponentAt(int, int) メソッドを参照しています。

{@link #getComponentAt(int, int) getComponentAt} メソッドを使用します。

標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。 

<a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。

この HTML は、Web ページ上では次のように表示されます。 

getComponentAt メソッドを使用します。

{@link} を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link オプションを使用します。

詳細については、{@link} タグのドキュメントを参照してください。

{@linkplain  package.class#member  label}
リンクのラベルがコードフォントではなくプレーンテキストで表示される点以外は {@link} と同じです。ラベルがプレーンテキストで記述されていると便利です。例: 
     {@linkplain add() the overridden method} を参照してください。

これは以下のように表示されます。

the overridden method を参照してください。

{@literal  text}
テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、text を表示します。これにより doc コメントでは、パラメータの種類 (<Object>)、不等号 (3 < 4)、または矢印 (<-) などで、HTML エンティティー (< および >) ではなく、通常の山括弧 (< および >) を使用できます。たとえば doc コメントのテキスト 
     {@literal A<B>C}

は、生成された HTML ページはブラウザで次のようにそのまま表示されます。

     A<B>C

注目すべき点として、<B> は太字であると解釈されません (コードフォントにならない)。

コードフォントで同じ機能を実現するには、{@code} を使用します。

@param  parameter-name description
指定した parameter-name と指定した description を使用してパラメータを「Parameters」セクションに追加します。doc コメントを記述するときは、description を複数行に続けることができます。このタグは、メソッド、コンストラクタ、またはクラスの doc コメント内でのみ有効です。

parameter-name は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタのタイプパラメータの名前になります。山括弧でパラメータ名を囲むと、型パラメータを使用することを指定します。

クラスの型パラメータの例:

     /**
      * @param <E> Type of element stored in a list
      */
     public interface List<E> extends Collection<E> {
     }

メソッドの型パラメータの例:

     /**
      * @param string  the string to be converted
      * @param type    the type to convert the string to
      * @param <T>     the type of the element
      * @param <V>     the value of the element
      */
     <T, V extends T> V convert(String string, Class<T> type) {
     }

詳細については、@param タグのドキュメントを参照してください。

@return  description
[戻り値] セクションを追加して、description のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。

詳細については、@return タグのドキュメントを参照してください。

@see   reference
[関連項目] 見出しを追加し、reference を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の @see タグを指定できます。 すべての @see タグの内容は、同じの見出しの下にグループ化されます。@see タグには、次の 3 種類の形式があります。 もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバーに対するインラインリンクを文中に挿入する方法は、{@link} を参照してください。
@see "string"
string のテキストエントリを追加します。リンクは生成されません。string は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (") かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。 
     @see "The Java Programming Language"

これは次のようなテキストを生成します。

関連項目:
The Java Programming Language
@see <a href="URL#value">label</a>
URL#value で定義されたとおりにリンクを追加します。URL#value は、相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (<) かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。 
     @see <a href="spec.html#section">Java Spec</a>

これは次のようなリンクを生成します。

関連項目:
Java Spec

@see  package.class#member  label
指定された名前を持つ、参照されている Java 言語のメンバーについてのドキュメントを指すリンクを、表示テキスト label とともに追加します。label は省略可能です。 label を省略すると、リンク先のメンバーの名前が適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。

バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。 1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。

  • package.class#member には、参照されている任意の有効なプログラム要素の名前を指定します。 つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。 ただし、メンバー名ーの前のドットは、シャープ記号 (#) で置き換えます。class は、任意のトップレベルまたは入れ子にされたクラスまたはインタフェースを表します。member は、任意のコンストラクタ、メソッドまたはフィールド (入れ子にされたクラスまたはインタフェースではない) を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、-link オプションを使います。参照クラスに属していない名前のドキュメントを参照するには、ほかの 2 つの形式の @see タグを使います。この引数については、このあとの「名前の指定」で詳しく説明します。
  • label は、省略可能なテキストで、リンクのラベルとして表示されます。label には空白を含めることができます。label を省略すると、package.class.member が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。
  • 空白文字は、package.class#member と label の間の区切り文字です。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。

例 - この例では、Character クラスにある @see タグが、String クラスの equals メソッドを参照しています。タグには、名前 String#equals(Object) とラベル equals の両方の引数が含まれています。

 /**
  * @see String#equals(Object) equals
  */

標準ドックレットは、次のような HTML を生成します。 

<dl>
<dt><b>See also:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>

これは、ブラウザでは次のように表示され、ラベルがリンクテキストになります。

関連項目:
equals

名前の指定 - このタグに指定する package.class#member という名前は、java.lang.String#toUpperCase() のように完全指定することも、String#toUpperCase() や #toUpperCase() のように部分的に指定することもできます。名前が完全指定されていない場合、Javadoc ツールは、Java コンパイラの通常の検索順序でその名前を検索します。詳細は、このあとの「@see の検索順序」を参照してください。名前には、メソッドの複数の引数の間など、括弧の内側であれば空白を含めることができます。

「部分的に指定」した短い名前を指定することの利点は、入力する文字数が減ることや、ソースコードが読みやすくなることです。次の表に、さまざまな形式の名前を示します。 この表の中で、Class にはクラスまたはインタフェースを、Type にはクラス、インタフェース、配列、または基本データ型を、そして method にはメソッドまたはコンストラクタを指定できます。

@see package.class#member の一般的な形式
現在のクラスのメンバーを参照する
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
現在の、またはインポートされたパッケージの別のクラスを参照する
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class
別のパッケージの要素を参照する (完全修飾)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

上の表に対する補足事項を次に示します。

@see の検索順序 - Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html または package-info.java)、または概要ファイル (overview.html) の中に登場する @see タグを処理します。後者の 2 つのファイルでは、完全指定の名前を @see タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。

Javadoc ツールは、.java ファイル内で完全指定でない名前が記述された @see タグを見つけると、Java コンパイラと同じ順序で指定された名前を検索します。 ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。 これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順序は、Java 言語仕様第 2 版の第 6 章「Names」で正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。

  1. 現在のクラスまたはインタフェース
  2. 外側を囲んでいるクラスとインタフェース (もっとも近いものから検索)
  3. スーパークラスとスーパーインタフェース (もっとも近いものから検索)
  4. 現在のパッケージ
  5. インポートされているパッケージ、クラス、およびインタフェース (import 文の順序に従って検索)

Javadoc ツールは、各クラスについて手順 1 〜 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。手順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。 その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。 このパッケージは、すべてのプログラムに自動的にインポートされるからです。

Javadoc ツールは、必ずしもサブクラスを検索するとは限りません。 また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、@see タグが java.awt.event.KeyEvent クラス内にあって、java.awt パッケージにある名前を参照している場合、Javadoc は、そのクラスがインポートしないかぎりそのパッケージを検索しません。

名前が表示される方法 - label を省略すると、package.class.member が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、String.toUpperCase() メソッドに、同じクラスのメンバーへの参照とほかのクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。

パッケージ名を広域的に削除するには、-noqualifier を使用します。

参照の種類 String.toUpperCase() での例 表示される名前
@see タグが同じクラスのメンバーを参照している @see String#toLowerCase() toLowerCase() (クラス名は省略)
@see タグが別のクラスのメンバーを参照している @see Character#toLowerCase(char) Character.toLowerCase(char) (パッケージ名は省略し、クラス名を含む)
@see タグが別のクラスのメンバーを参照している @see java.io.File#exists() java.io.File.exists() (パッケージ名とクラス名を含む)

@see の例
右側のコメントは、@see タグが別のパッケージ (java.applet.Applet など) のクラス内にある場合に、名前がどのように表示されるかを示しています。

                                           関連項目: 
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"

@see を、ドキュメント化の対象にしていないクラスにまで拡張するには、-link オプションを使用します。

詳細については、@see タグのドキュメントを参照してください。

@serial  field-description | include | exclude
デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。

field-description (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式のページに追加します。

クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。

include および exclude 引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。

例: javax.swing パッケージは、@serial exclude で指定されています (package.html または package-info.java 内)。public クラス java.security.BasicPermission は、@serial exclude で指定されています。package private クラス java.util.PropertyPermissionCollection は、@serial include で指定されています。

クラスレベルで指定された @serial タグは、パッケージレベルで指定された @serial タグをオーバーライドします。

これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、「直列化の FAQ」も参照してください。 この FAQ には、「-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、「Sun の仕様」も参照してください。

@serialField  field-name  field-type  field-description
Serializable クラスの serialPersistentFields メンバーの ObjectStreamField コンポーネントをドキュメント化します。各 ObjectStreamField コンポーネントに対して @serialField タグを 1 つ使う必要があります。

@serialData  data-description
data-description は、直列化された形式でのデータの型と順序を説明するテキストです。このデータには、特に、writeObject メソッドによって書き込まれる省略可能なデータ、および Externalizable.writeExternal メソッドによって書き込まれるすべてのデータ (基底クラスを含む) が含まれます。

@serialData タグは、writeObject、readObject、writeExternal、readExternal、writeReplace、および readResolve メソッドのドキュメンテーションコメントで使用できます。

@since  since-text
生成ドキュメントに [導入されたバージョン] 見出しを追加し、指定された since-text を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、since-text に示されたソフトウェアリリース以降、存在していることを意味します。例を示します。 
    @since 1.5

Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。 その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。

@throws  class-name  description 
@throws タグと @exception タグは同義です。生成ドキュメントに [例外] 小見出しを追加して、class-name と description テキストを書き込みます。class-name は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタの doc コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に従ってクラスを探します。同じまたは異なる例外の doc コメントで、複数の @throws タグを使用できます。

すべてのチェック済み例外がドキュメント化されるようにするために、@throws タグが throws 節内の例外用に存在しない場合は、@throws タグのあるドキュメントであるかのように、Javadoc ツールによって例外が HTML 出力に説明なしで自動的に追加されます。

オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、@throws ドキュメンテーションをそのメソッドからサブクラスにコピーされます。インタフェースメソッドから実装メソッドにコピーされる場合も同様です。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。

詳細については、@throws タグのドキュメントを参照してください。

{@value  package.class#field}
{@value} が静的フィールドの doc コメントで 引数なしで使用されている場合、その定数の値が表示されます。 
    /**
     * The value of this constant is {@value}.
     */
    public static final String SCRIPT_START = "<script>"

任意の doc コメント内で引数 package.class#field ありで使用されている場合は、指定した定数の値が表示されます。 

    /**
     * Evaluates the script starting with {@value #SCRIPT_START}.
     */
    public String evalScript(String script) {
    }

引数 package.class#field は、@see 引数と同一の形式になります。ただし、メンバーが静的フィールドになければならない点が異なります。

これらの定数での値は、定数フィールド値ページにも表示されます。

@version  version-text
-version オプションが使われている場合、生成ドキュメントに [バージョン] 小見出しを追加して、指定された version-text を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。 これに対し、@since は、このコードが導入されたバージョン番号を保持します。version-text には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。

1 つのドキュメンテーションコメントに複数の @version タグを含めることができます。必要に応じて、@version タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (,) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。

詳細については、@version タグのドキュメントを参照してください。

タグを使用できる場所

ここでは、タグを使用できる場所について説明します。@see、@since、@deprecated、{@link}、{@linkplain} および {@docroot} のタグは、すべての doc コメントで使用できます。

概要のドキュメンテーションタグ

概要タグは、概要ページのドキュメンテーションコメントで使用できるタグです。 このドキュメンテーションコメントは、通常 overview.html という名前ソースファイル内にあります。ほかのドキュメンテーションコメントの場合と同様に、これらのタグは、主説明のあとで使う必要があります。

注 - バージョン 1.2 では、概要ドキュメント内の {@link} タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、{@docRoot} タグは、概要ドキュメント内では動作しません。

概要タグ
@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}

パッケージドキュメンテーションタグ

パッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。 このドキュメンテーションコメントは、package.html または package-info.java という名前のソースファイル内にあります。ここで使用できる @serial タグは、include または exclude 引数を指定したものだけです。

パッケージタグ
@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}

クラスおよびインタフェースドキュメンテーションタグ

次に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる @serial タグは、include または exclude 引数を指定したものだけです。

クラスおよびインタフェースタグ
@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}

次にクラスコメントの例を示します。

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version 1.13, 06/08/06
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

フィールドドキュメンテーションタグ

次に、フィールドのドキュメンテーションコメントで使用できるタグを示します。

フィールドタグ
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}

次にフィールドコメントの例を示します。

    /**
     * The X-coordinate of the component.
     *
     * @see #getLocation()
     */
    int x = 1263732;

コンストラクタおよびメソッドドキュメンテーションタグ

次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で表示できるタグを示します。 ただし、@return はコンストラクタでは表示できず、{@inheritDoc} は表示に制限があります。@serialData タグは特定の直列化メソッドの doc コメントでのみ使用できます。

メソッドおよびコンストラクタタグ
@see
@since
@deprecated
@param
@return
@throws と @exception
@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot}

次にメソッドのドキュメンテーションコメントの例を示します。

    /**
     * Returns the character at the specified index. An index 
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException 
     *              if the index is not in the range <code>0</code> 
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

オプション

javadoc ツールは、ドックレットを使って出力を決定します。Javadoc ツールは、-doclet オプションでカスタムドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使います。Javadoc ツールには、任意のドックレットとともに使用できるコマンド行オプションがあります。 これらのオプションについては、このあとの「Javadoc オプション」で説明します。標準ドックレットでは、このほかに、いくつかの追加のコマンド行オプションが提供されます。 これらのオプションについては、そのあとの「標準ドックレットが提供するオプション」で説明します。どのオプション名も、大文字と小文字が区別されません。 ただし、オプションの引数では、大文字と小文字が区別されます。

オプションを次に示します。

-1.1
-author
-bootclasspath
-bottom
-breakiterator
-charset
-classpath
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-encoding
-exclude
-excludedocfilessubdir
-extdirs
-footer
-group
 -header
-help
-helpfile
-J
-keywords
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-overview
-package
 -private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-title
-use
-verbose
-version
-windowtitle

イタリックで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。

Javadoc オプション

-overview  path/filename
Javadoc に対して、path/filename で指定された「ソース」ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ (overview-summary.html) に配置するように指定します。path/filename は、-sourcepath への相対パスです。

filename と path には、それぞれ任意の名前と場所を指定できますが、通常は、overview.html という名前を付けて、ソースツリー内の最上位のパッケージディレクトリがあるディレクトリに配置します。この場所に配置すると、-sourcepath によってこのファイルが指し示されるので、パッケージをドキュメント化する際に path が不要になります。たとえば、java.lang パッケージのソースツリーが /src/classes/java/lang/ の場合、概要ファイルを /src/classes/overview.html に配置できます。「使用例」を参照してください。

path/filename で指定するファイルについては、「概要コメントファイル」を参照してください。

概要ページが作成されるのは、Javadoc に複数のパッケージ名を渡した場合だけです。詳細は、「HTML フレーム」を参照してください。

概要ページのタイトルは、-doctitle によって設定されます。

-public
public クラスおよびメンバーだけを表示します。

-protected
protected および public のクラスとメンバーだけを表示します。これはデフォルトの設定です。

-package
package、protected、および public のクラスとメンバーだけを表示します。

-private
すべてのクラスとメンバーを表示します。

-help
オンラインヘルプを表示します。 Javadoc とドックレットのコマンド行オプションが一覧表示されます。

-doclet  class
ドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。完全指定の名前を指定してください。このドックレットにより、出力の内容と形式が定義されます。-doclet オプションが使われていない場合、Javadoc は、標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには、start(Root) メソッドが含まれていなければなりません。この起動クラスへのパスは、-docletpath オプションによって定義されます。

たとえば、MIF ドックレットを呼び出すには、次のように指定します。

    -doclet com.sun.tools.doclets.mif.MIFDoclet

特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。

-docletpath  classpathlist
-doclet オプションで指定されているドックレット開始クラスファイル、およびそれが依存するすべての jar ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。classpathlist には、複数のパスまたは JAR ファイルを含めることができます。 その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。

jar ファイルへのパスの例には、ドックレット開始クラスファイルが含まれています。jar ファイル名が含まれている点に注目してください。

   -docletpath /home/user/mifdoclet/lib/mifdoclet.jar
ドックレット開始クラスファイルのパスの例。クラスファイル名が省略されている点に注目してください。 
   -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。

-1.1
この機能は、Javadoc 1.4 では削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。 入れ子のクラスはサポートされていません。このオプションが必要な場合は、Javadoc 1.2 または 1.3 を使用してください。

-source release
受け付けるソースコードのバージョンを指定します。release には次の値を指定できます。
1.5 Javadoc は、JDK 1.5 で導入された総称および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。
1.4 Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。
1.3 Javadoc は、JDK 1.3 以降に導入されたアサーション、総称、または他の言語機能をサポートしません。

javac でコードをコンパイルするときに使用した値に対応する release の値を使用します。

-sourcepath  sourcepathlist
javadoc コマンドにパッケージ名または -subpackages を渡すときに、ソースファイル (.java) を検索するためのパスを指定します。sourcepathlist には、コロン (:) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。

-sourcepath オプションは、javadoc コマンドにパッケージ名を渡すときにだけ使用できます。 javadoc コマンドに渡される .java ファイルは、このパスからは検索されません。.java ファイルを検索するには、そのファイルのあるディレクトリに cd によって移動するか、または各ファイルの先頭にパスを含めます (「1 つ以上のクラスのドキュメント化」を参照)。-sourcepath が省略された場合、Javadoc は、クラスパスを使ってソースファイルを検索します (-classpath を参照)。したがって、デフォルトの -sourcepath は、クラスパスの値です。-classpath も省略してパッケージ名を Javadoc に渡すと、Javadoc は現在のディレクトリおよびそのサブディレクトリからソースファイルを検索します。

sourcepathlist には、ドキュメント化するパッケージ名のソースツリーのルートディレクトリを設定します。たとえば、com.mypackage というパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。

  /home/user/src/com/mypackage/*.java
この場合、次のようにして sourcepath を /home/user/src、つまり com/mypackage を含むディレクトリに指定し、それからパッケージ名 com.mypackage を指定します。 
  % javadoc -sourcepath /home/user/src/ com.mypackage
この方法は、ソースパスの値とパッケージ名を連結して、ドットを (円記号) 「\」に変えると、パッケージのフルパス (C:\user\src\com\mypackage) になることを理解すると簡単です。/home/user/src/com/mypackage.

2 つのソースパスを設定するには、次のようにします。

  % javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage

-classpath  classpathlist
Javadoc が参照クラス (.class ファイル) を検索するパスを指定します。 参照クラスとは、ドキュメント化されるクラスとそれらのクラスによって参照されるすべてのクラスのことです。classpathlist には、コロン (:) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパスの以下すべてのサブディレクトリを検索します。classpathlist を指定するときは、クラスパスのドキュメントにある指示に従ってください。

-sourcepath が省略されている場合、Javadoc ツールは、-classpath を使って、クラスファイルだけでなくソースファイルも検索します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、-sourcepath と -classpath の両方を使います。

たとえば、com.mypackage をドキュメント化する場合に、ソースファイルがディレクトリ /home/user/src/com/mypackage にあり、このパッケージが /home/user/lib 内のライブラリを使うのであれば、次のように指定します。

  % javadoc -classpath /home/user/lib -sourcepath /home/user/src com.mypackage
ほかのツールと同様に、-classpath が指定されていない場合は、CLASSPATH 環境変数が設定されていれば、Javadoc ツールはこの環境変数を使います。どちらも設定されていない場合、Javadoc ツールは現在のディレクトリからクラスを検索します。

Javadoc ツールは拡張機能クラスおよびブートストラップクラスに関連しているため、Javadoc ツールが -classpath を使用してユーザークラスを検索する方法についての詳細は、「クラスの検索方法」をご覧ください。

便宜上、* のベース名を含むクラスパス要素は、ディレクトリ内の拡張子 .jar または .JAR を持つすべてのファイルのリストを指定するのと同じとみなされます (Java プログラムはこの 2 つの呼び出しを区別できない)。

たとえば、ディレクトリ foo に a.jar と b.JAR が含まれている場合、クラスパス要素 foo/* は A.jar:b.JAR に展開されます。 ただし、JAR ファイルの順番は指定されません。このリストには、隠しファイルも含め、指定されたディレクトリ内のすべての JAR ファイルが含まれます。* だけから成るクラスパスエントリは、カレントディレクトリ内のすべての JAR ファイルのリストに展開されます。CLASSPATH 環境変数も、定義時には同様に展開されます。クラスパスのワイルドカード展開は必ず、Java 仮想マシンの起動前に実行されます。したがって、System.getenv("CLASSPATH") 呼び出しのように環境に問い合わせを行わない限り、Java プログラムが展開されていないワイルドカードを認識することはありません。

-subpackages  package1:package2:...
ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 package 引数は、任意の最上位サブパッケージ (java など) または完全指定のパッケージ (javax.swing など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、-sourcepath を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。

例を示します。

  % javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。

-exclude とともに -subpackages を使用すると、特定のパッケージを除外できます。

-exclude  packagename1:packagename2:...
指定されたパッケージとそのサブパッケージを -subpackages によって作成されたリストから無条件に除外します。過去の -subpackages オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。例を示します。 
  % javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
このうち、java.io、java.util、java.math は組み込まれますが、java.net と java.lang 以下のパッケージは除外されます。ただし、java.lang のサブパッケージである java.lang.ref は除外されます。

-bootclasspath  classpathlist
ブートクラスが存在するパスを指定します。ブートクラスとは、通常、Java プラットフォームのコアクラスのことです。ブートクラスパスは、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、「javac と javadoc がクラスを検索する方法」を参照してください。classpathlist 内の複数のディレクトリは、コロン (:) で区切ります。

-extdirs  dirlist
拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java 拡張機能機構を使うすべてのクラスです。extdirs は、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、前述の -classpath を参照してください。dirlist 内の複数のディレクトリは、コロン (:) で区切ります。

-verbose
javadoc の実行中に詳細なメッセージを表示します。verbose オプションを指定しないと、ソースファイルのロード時、ドキュメントの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。verbose オプションを指定すると、各 Java ソースファイルの解析に要した時間 (ミリ秒単位) など、追加のメッセージが表示されます。

-quiet
エラーメッセージまたは警告メッセージ以外のメッセージを抑制し、警告とエラーだけが表示されるようにして、これらを特定しやすくします。バージョン文字列も抑制します。

-breakiterator 
英語言語というロケール固有のアルゴリズムではなく、java.text.BreakIterator の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでに BreakIterator を使用)。「最初の文」とは、パッケージ、クラス、またはメンバーの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバーの要約にコピーされ、アルファベット順のインデックスにコピーされます。

JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、-breakiterator オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。

  • 英文のデフォルトの文区切りアルゴリズム - 空白または HTML ブロックタグ (<P> など) が続くピリオドで停止する
  • breakiterator 文区切りアルゴリズム - 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する

注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。 この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。

-locale  language_country_variant

重要 - -locale オプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このコマンド行オプションだけは、指定する順序に依存します。

Javadoc がドキュメントを生成するときに使うロケールを指定します。引数には、java.util.Locale のドキュメントで説明されているロケールの名前を指定します。たとえば、en_US (英語、米国)、en_US_WIN (Windows で使われる英語) などを指定します。

ロケールを指定すると、指定したロケールのリソースファイルが Javadoc によって選択されて、メッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) のために使われます。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を判別するための文の区切り文字も、指定したロケールによって決まります。ただし、このオプションは、ドキュメント化されるクラスのソースファイル内で指定されているドキュメンテーションコメントのテキストのロケールを決定するものではありません。

-encoding  name
ソースファイルのエンコーディングの名前 (EUCJIS/SJIS など) を指定します。このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。

-docencoding および -charset も参照してください。

-Jflag
javadoc を実行する実行時システム java に、flag を直接渡します。J と flag の間に空白を入れてはなりません。たとえば、生成ドキュメントを処理するためにシステムで 32M バイトのメモリーを確保しておく必要がある場合は、Java の -Xmx オプションを次のように呼び出します。 -Xms は、省略可能です。 これは、初期メモリーのサイズを設定するだけのオプションで、必要なメモリーの最小サイズがわかっている場合に便利です。 
   % javadoc -J-Xmx32m -J-Xms32m com.mypackage
使用している javadoc のバージョンを確認するには、次のように java の「-version」オプションを呼び出します。 
   % javadoc -J-version
   java version "1.2"
   Classic VM (build JDK-1.2-V, green threads, sunwjit)
出力ストリームには標準ドックレットのバージョン番号が含まれます。

標準ドックレットが提供するオプション

-d  directory
生成された HTML ファイルを保存する生成先ディレクトリを指定します(「d」は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 directory には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。バージョン 1.4 では、javadoc を実行すると生成先ディレクトリが自動的に作成されます。

たとえば、次の例では、com.mypackage パッケージのドキュメントを生成し、結果を /home/user/doc/ ディレクトリに保存します。

  % javadoc -d /home/user/doc com.mypackage

-use
ドキュメント化されるクラスおよびパッケージごとに 1 つの [使用] ページを組み込みます。このページには、その特定のクラスまたはパッケージの API を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラス C を例にとると、クラス C を使っているものとしては、C のサブクラス、C として宣言されているフィールド、C を返すメソッド、および、型 C のパラメータを持つメソッドとコンストラクタがあります。

たとえば、String の [使用] ページに何が表示されるかを見てみましょう。java.awt.Font クラスの getName() メソッドは、String 型を返します。したがって、getName() は String を使っているので、String の [使用] ページにはこのメソッドがあります。

ただし、ドキュメント化されるのは API の使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中で String を使っていても、引数として文字列をとったり、文字列を返したりしない場合は、String の「使用」とはみなされません。

生成された [使用] ページにアクセスするには、目的のクラスまたはパッケージに移動し、ナビゲーションバーの [使用] リンクをクリックします。

-version
生成ドキュメントに、@version のテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している Javadoc ツールのバージョンを確認するには、-J-version オプションを使用します。

-author
生成ドキュメントに、@author のテキストを組み込みます。

-splitindex
索引ファイルをアルファベットごとに複数のファイルに分割し、文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる索引エントリ用に 1 つのファイルを作成します。

-windowtitle  title
HTML の <title> タグに配置するタイトルを指定します。指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。このタイトルには HTML タグを含めないでください。 タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。title の中で引用符を使う場合は、引用符をエスケープする必要があります。-windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに -doctitle の値を使います。 
  % javadoc -windowtitle "Java 2 Platform" com.mypackage
-doctitle  title
概要ファイルの最上部の近くに配置するタイトルを指定します。タイトルは中央揃えになり、レベル 1 の見出しとして、上部ナビゲーションバーのすぐ下に置かれます。title には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。title の中で引用符を使う場合は、引用符をエスケープする必要があります。 
  % javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" com.mypackage
-title  title
このオプションは、現在は存在しません。Javadoc 1.2 のベータ版にだけ存在しました。このオプションは、-doctitle という名前に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。

-header  header
各出力ファイルの上端に配置するヘッダーテキストを指定します。ヘッダーは、上部ナビゲーションバーの右側に配置されます。header には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。header の中で引用符を使う場合は、引用符をエスケープする必要があります。 
  % javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage

-footer  footer
各出力ファイルの下端に配置するフッターテキストを指定します。フッターは、下部ナビゲーションバーの右側に配置されます。 footer には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。footer の中で引用符を使う場合は、引用符をエスケープする必要があります。

-bottom  text
各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーより下の、ページの最下部に配置されます。text には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。text の中で引用符を使う場合は、引用符をエスケープする必要があります。

-link  extdocURL
javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数を 1 つとります。

  • extdocURL は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。あとで例を示します。このディレクトリ内にパッケージリストファイルが存在していなければなりません。 存在しない場合は、-linkoffline を使用します。Javadoc ツールは、パッケージリストファイルからパッケージ名を読み取り、これらのパッケージをその URL にリンクします。Javadoc ツールを実行すると、作成される <A HREF> リンク内に extdocURL の値がそのままコピーされます。したがって、extdocURL はファイルへの URL ではなく「ディレクトリへの URL」でなければなりません。

    extdocURL への絶対リンクを使用すると、ユーザーのドキュメントを任意の Web サイト上のドキュメントにリンクできます。 相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクを使用する場合、-d を使って、生成先ディレクトリからリンクされるパッケージのあるディレクトリの相対パスを指定する必要があります。

    通常、絶対リンクを指定する場合は、http:リンクを使用します。Web サーバーを持たないファイルシステムにリンクする場合は、file: リンクを使用できます。ただし、この方法は、すべてのユーザーが生成された同じファイルシステムを共有するドキュメントにアクセスする必要がある場合以外は使用しないでください。

    いかなる場合にも、いかなるオペレーティングシステムでも、絶対 URL か相対 URL か、「http:」ベースか「file:」ベースかにかかわらず、スラッシュを区切り文字として使用します (URL Memo で指定)。

    http:ベースの絶対リンク:
    -link http://<host>/<directory>/<directory>/.../<name>
    file:ベースの絶対リンク:
    -link file://<host>/<directory>/<directory>/.../<name>
    相対リンク:
    -link <directory>/<directory>/.../<name>

javadoc の実行時に複数の -link オプションを指定して、複数のドキュメントへのリンクを作成することもできます。

-linkoffline または -link の選択
-link を使用する場合:
  • 外部 API ドキュメントへの相対パスを使用する場合
  • 外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されている場合)
次のような場合は、-linkoffline オプションを使用します。
  • プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されていない場合に外部 API ドキュメントへの絶対 URL を使用する場合。このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。

外部ドキュメントへの絶対リンクの使用例 - http://java.sun.com/j2se/1.5.0/docs/api 内の java.lang、java.io、その他の Java 2 プラットフォームパッケージにリンクしたい場合があります。 次のコマンドは、com.mypackage パッケージのドキュメントと Java 2 プラットフォームパッケージへのリンクを生成します。生成されたドキュメントには、たとえばクラスツリー内の Object クラスへのリンクが含まれています。-sourcepath や -d などの他のオプションは表示されません。

  % javadoc -link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage
外部ドキュメントへの相対リンクの使用例 - 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。 さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、2 つのパッケージは、API である com.apipackage とSPI (サービスプロバイダインタフェース) である com.spipackage です。ドキュメントの格納先は docs/api/com/apipackage パッケージと docs/spi/com/spipackage パッケージです。API パッケージのドキュメントがすでに生成されていて、現在のディレクトリが docs である場合、次のコマンドを実行することによって、この API ドキュメントへのリンクを持つ SPI パッケージをドキュメント化します。 
  % javadoc -d ./spi -link ../api com.spipackage

-link 引数は、生成先ディレクトリ (docs/spi) の相対パスです。

詳細 - -link オプションを使うと、「コードからは参照されていても、Javadoc の今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらの HTML ページがある場所を調べ、その場所を extdocURL に指定する必要があります。このオプションを使うと、たとえば、サードパーティーのドキュメントから、http://java.sun.com にある java.* のドキュメントにリンクすることができます。

今回の実行で Javadoc によって生成されるドキュメント内の API だけを対象にリンクを作成する場合は、-link オプションを省略します。-link オプションが指定されていない場合、Javadoc ツールは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。

このオプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。

また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに対して javadoc を実行し、これら 2 つのパッケージ群の間にクロスリンクを作成できます。

クラスの参照方法 - 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。import 文または宣言で参照する必要があります。次に、クラス java.io.File を参照する方法の例を示します。

  • すべての種類の import 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または java.lang.* に対する自動的なインポート。たとえば、次のようにすれば十分です。
    import java.io.*;
    1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、自動インポート java.lang.* も使用できません。
  • 宣言の場合:
    void foo(File f) {}
    この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、implements、extends、または throws 文に置きます。

この結果、-link オプションを使用しても、この制限のために誤って表示されない多くのリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。

パッケージリスト - -link オプションは、package-list という名前のファイルを要求します。 このファイルは、Javadoc ツールによって生成され、-link によって指定した URL に存在します。package-list ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキストファイルです。前の例では、Javadoc ツールは指定された URL にある package-list という名前のファイルを探し、パッケージ名を読み込んで、その URL にあるそれらのパッケージへのリンクを作成しました。

たとえば、Java プラットフォーム v5.0 API のパッケージリストは http://java.sun.com/j2se/1.5.0/docs/api/package-list にあり、次のような内容で始まっています。

  java.applet  
  java.awt
  java.awt.color
  java.awt.datatransfer
  java.awt.dnd
  java.awt.event
  java.awt.font
  その他 ...

-link オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、-link オプションを指定した場合は、指定した extdocURL にある package-list ファイルから該当するパッケージ名が検索されます。パッケージ名が見つかると、extdocURL が名前の前に付加されます。

すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定した URL に存在していなければなりません。Javadoc ツールは、指定された package-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。

複数のリンク - 複数の -link オプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。Javadoc 1.2 には、複数の -link オプションを指定できないというバグがあります。これは 1.2.2 で修正されました。

リンクする外部ドキュメントごとに、次のように別々のリンクオプションを指定します。

   % javadoc -link extdocURL1 -link extdocURL2 ...-link extdocURLn com.mypackage

extdocURL1、extdocURL2、... extdocURLn は、それぞれ外部ドキュメントのルートを指し、各ルートには package-list という名前のファイルが入っています。

クロスリンク - まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラップ」が必要になります。つまり、どのドキュメントについても package-list が存在していない場合は、最初のドキュメントに対して javadoc ツールを実行する時点で、2 番目のドキュメントの package-list がまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあとで、最初のドキュメントを生成し直す必要があります。

この場合、最初のドキュメント生成の目的は、そのドキュメントの package-list を作成することです。 パッケージ名をすべて把握している場合は、package-list を手動で作成することもできます。次に、2 番目のドキュメントとその外部リンクを生成します。必要な外部の package-list ファイルが存在しない場合、Javadoc ツールは警告を表示します。

-linkoffline  extdocURL  packagelistLoc
このオプションは、-link オプションを変えたものです。 どちらも、javadoc によって生成された外部参照クラスのドキュメントへのリンクを作成します。Javadoc ツール自体がオフラインになっているとき (Web 接続を使ってドキュメントにアクセスできないとき)、Web 上のドキュメントにリンクするには、-linkoffline オプションを使用します。

厳密には、外部ドキュメントの package-list ファイルにアクセスできないとき、またはこのファイルが extdocURL で指定された場所とは異なる場所 (通常、packageListLoc で指定可能なローカルな場所) に存在するとき、-linkoffline を使用します。したがって、extdocURL に WWW 上でしかアクセスできない場合は、-linkoffline を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。

さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。 こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。

-linkoffline オプションは引数を 2 つ取ります。 最初の引数は <a href> リンクに組み込まれる文字列を指定する引数、2 番目の引数は package-list の検索場所を指定する引数です。

  • extdocURL は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。相対リンクを使用する場合、-d を使って、生成先ディレクトリからリンクされるパッケージのルートの相対パスを指定する必要があります。詳細は、-link オプションの extdocURL を参照してください。
  • packagelistLoc には、外部ドキュメントの package-list ファイルが入っているディレクトリのパスまたは URL を指定します。これは、URL (http: または file:)or file:)とファイルパスのどちらでもかまいません。また、絶対パスと相対パスのどちらでも指定できます。相対パスの場合は、javadoc が実行されるカレントディレクトリからの相対パスとして指定します。package-list というファイル名は含めないでください。

javadoc の 1 回の実行で、複数の -linkoffline オプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。

外部ドキュメントへの絶対リンクを使った例 - http://java.sun.com/j2se/1.5.0/docs/api 内の java.lang、java.io、、およびその他の Java 2 プラットフォームパッケージにリンクしたくても、Web にアクセスできない 場合について考えてみます。この場合は、ブラウザで http://java.sun.com/j2se/1.5.0/docs/api/package-list にある package-list ファイルを開き、ローカルディレクトリに保存します。 さらに、2 番目の引数 packagelistLoc にこのローカルコピーの場所を指定します。この例では、パッケージリストファイルはカレントディレクトリ "." に保存されています。次のコマンドは、Java 2 プラットフォーム API へのリンクを含む、com.mypackage パッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の Object クラスへのリンクが含まれています。-sourcepath などの他の必要なオプションは表示されません。

% javadoc -linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage

外部ドキュメントへの相対リンクの使用例 - 通常、-linkoffline に相対パスを指定することはありません。 -link で同じことができるからです。-linkoffline を使用する際、package-list には通常ローカルのファイルを指定します。 相対リンクを使用する際も、リンク先のファイルには通常ローカルのファイルを指定します。したがって、-linkoffline の 2 つの引数に別々のパスを指定する必要はありません。2 つの引数が同一である場合は、-link を使用できます。-link の相対リンクの例を参照してください。

package-list ファイルを手動で作成 - package-list ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、packagelistLoc でそのパスを指定することができます。com.apipackage が最初に生成され、com.spipackage のパッケージリストが存在しないという前出の例を参照してください。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、package-list ファイルが生成されない Javadoc 1.0 や 1.1 などで生成されたパッケージ向けに package-list ファイルを作成するときにも、この方法を利用します。同様に、2 つの会社が未公開の package-list ファイルを共有することもできるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能です。

複数のドキュメントへのリンク - -linkoffline は、参照先の生成ドキュメントごとに 1 つずつ指定します。 次の例では、わかりやすくするためにオプションごとに行を分けています。

% javadoc -linkoffline extdocURL1 packagelistLoc1 \
          -linkoffline extdocURL2 packagelistLoc2 \
          ...

ドキュメントの更新 - 前述の -linkoffline オプションのもうひとつの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバーのリスト、[使用] ページなどの場所で、リンクが壊れることがあります。

まず、今回の実行で使用する新しい生成先ディレクトリ (update) を作成します。元の生成先ディレクトリの名前が html だとします。もっとも単純な例では、html ディレクトリの親ディレクトリに移動 (cd) します。-linkoffline の最初の引数にカレントディレクトリ "." を指定し、2 番目の引数に html への相対パスを指定します。 ここで、package-list が検索されます。 更新対照のパッケージのパッケージ名だけを指定してください。

  % javadoc -d update -linkoffline . html com.mypackage
Javadoc ツールの終了後、update/com/package 内の生成されたクラスのページをコピーし (概要や索引を除く)、html/com/package 内の元のファイルに上書きします。

-linksource 
各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。

このオプションは、-public、-package、-protected、-private の各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソースファイル内のすべての非公開実装の詳細を公開します。-private オプションを指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。

各リンクは、その宣言内の識別子名の上に作成されます。たとえば、Button クラスのソースコードヘのリンクは、「Button」という語の上に作成されます。

    public class Button
    extends Component
    implements Accessible
Button クラスの getLabel() メソッドのソースコードへのリンクは、「getLabel」という語の上に作成されます。 
    public String getLabel()

-group  groupheading  packagepattern:packagepattern:...
概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の -group オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。 各グループ内では、パッケージがアルファベット順に並べられます。指定した -group オプションごとに、packagepattern 式のリストと一致するパッケージが、見出し groupheading を持つ 1 つの表にまとめて表示されます。
  • groupheading には、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。
  • packagepattern には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (*) を指定できます。アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして指定できるのは、アスタリスクだけです。1 つのグループには、コロン (:) で区切って複数のパターンを含めることができます。

注: パターンやパターンリスト内でアスタリスクを使う場合は、"java.lang*:java.util" のように、パターンリストを引用符で囲む必要があります。

-group オプションが指定されていない場合は、すべてのパッケージが、「パッケージ」という見出しの 1 つのグループに入れられます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。

たとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。「java.lang*」では、最後のドットを指定していないことに注目してください。 「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。

  % javadoc -group "Core Packages" "java.lang*:java.util"
            -group "Extension Packages" "javax.*"
            java.lang java.lang.reflect java.util javax.servlet java.new
この結果、次のようなグループ化が行われます。
コアパッケージ
java.lang
java.lang.reflect
java.util
拡張機能パッケージ
javax.servlet
その他のパッケージ
java.new

-nodeprecated
推奨されない API をドキュメントに生成しないようにします。このオプションを指定すると、-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、推奨されない API が生成されません。このオプションは、コードを記述しているとき、推奨されないコードによって気を散らされたくない場合に便利です。

-nodeprecatedlist
推奨されない API のリストを含むファイル (deprecated-list.html)、およびナビゲーションバーのそのページへのリンクが生成されないようにします。ただし、ドキュメントのほかの部分では、推奨されない API が生成されます。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。

-nosince
生成ドキュメントから、@since タグに対応する「導入されたバージョン」 セクションを省略します。

-notree
生成されるドキュメントからクラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。

-noindex
生成ドキュメントから、索引を省略します。デフォルトでは、索引が生成されます。

-nohelp
出力の各ページの最上部と最下部にあるナビゲーションバーから [ヘルプ] リンクを省略します。

-nonavbar
生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダー、およびフッターを生成しないようにします。このオプションは、bottom オプションには影響を与えません。-nonavbar オプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要で、ナビゲーションの必要がない場合に便利です。

-helpfile  path/filename
上部と下部のナビゲーションバーの [ヘルプ] リンクのリンク先となる代替ヘルプファイル path/filename のパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているヘルプファイル help-doc.html を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。filename にはどんなファイル名でも指定でき、help-doc.html には限定されません。例を示します。 
  % javadoc -helpfile /home/user/myhelp.html java.awt
-stylesheetfile  path/filename
代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているスタイルシートファイル stylesheet.css を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。filename にはどんなファイル名でも指定でき、stylesheet.css には限定されません。例を示します。 
  % javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage
-serialwarn
@serial タグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2 以降のバージョンでは、直列化の警告は生成されません。1.2.2 より前の初期バージョンでは、警告が生成されます。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと writeExternal メソッドを適切にドキュメント化するのに役立ちます。

-charset  name
このドキュメント用の HTML 文字セットを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。例を示します。 
  % javadoc -charset "iso-8859-1" mypackage
生成されるすべてのページの先頭に、次の行が挿入されます。 
   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
この META タグについては、HTML の標準 (4197265 および 4137321) を参照してください。

-encoding および -docencoding も参照してください。

-docencoding  name
生成される HTML ファイルのエンコーディングを指定します。この名前は、IANA Registry で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら -encoding を使用した場合、生成される HTML ファイルのエンコードは、-encoding によって決められます。例: 
  % javadoc -docencoding "ISO-8859-1" mypackage
-encoding および -charset も参照してください。

-keywords
HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。 一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。

メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。

     <META NAME="keywords" CONTENT="java.lang.String class">
     <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
     <META NAME="keywords" CONTENT="length()">
     <META NAME="keywords" CONTENT="charAt()">

-tag  tagname:Xaoptcmf:"taghead"
Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ @tagname を解釈できるようにします。これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内のすべてのカスタムタグに -tag オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、X を付けて無効にします。

コロン (:) は常に区切り文字になります。tagname でコロンを使用するには、「タグ名でのコロンの使用」を参照してください。

-tag オプションは、タグの見出し「taghead」を太字で出力します。 その次の行には、このオプションの引数で指定したテキストが続きます。 以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。 このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (@return、@author など) の出力とよく似ています。taghead を省略すると、tagname が見出しとして表示されます。

タグの配置 - 引数の Xaoptcmf 部分は、ソースコード内のタグを配置できる位置と、X を使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合は a を指定します。 それ以外の文字の組み合わせも可能です。

X (タグの無効化)
a (すべての位置)
o (概要)
p (パッケージ)
t (型すなわちクラスおよびインタフェース)
c (コンストラクタ)
m (メソッド)
f (フィールド)

シングルタグの例 - ソースコード内の任意の位置で使用で気るタグのタグオプションの例を示します。

    -tag todo:a:"To Do:"
@todo をコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。 
    -tag todo:cmf:"To Do:"
上の例の最後のコロン (:) は、パラメータ区切り子ですが、見出しテキストの一部になっています (以下の例を参照)。次の例のように、@todo タグを含むソースコードでは、いずれかのタグオプションを使用します。 
     @todo The documentation for this method needs work.
タグ名にコロンを使用する - コロン (:) をバックスラッシュでエスケープすると、コロンをタグ名に使用することができます。このドキュメンテーションコメントの中では、次のように使用します。 
    /**
     * @ejb:bean
     */
でこのタグオプションを使用すると、 
    -tag ejb\\:bean:a:"EJB Bean:"
タグ名のスペルチェック (タグの無効化) - ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタグを有効にし、出力を抑制するタグを無効にします。タグを無効にするには、X を指定します。指定しないと、そのタグは有効になります。 これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。

すでに配置されている値に X を追加できます。 こうしておけば、X を削除するだけでタグを有効にすることができます。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。

    -tag todo:Xcmf:"To Do:"
さらに単純な指定方法もあります。 
    -tag todo:X

構文 -tag todo:X は、@todo が taglet で定義されている場合も有効です。

タグの順序 - -tag (および -taglet) オプションの順序によって、その出力順序が決定します。カスタムタグと標準タグを組み合わせて使用することもできます。標準タグのタグオプションは、順序を決定するためだけのプレースホルダです。これらは標準タグ名のみを使用します。(標準タグの小見出しは変更できません。)これについては、以下の例で説明します。

-tag がない場合、-taglet の位置によってその順序が決定します。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、-taglet と -tag の両方が todo という名前を持っている場合、コマンド行の最後にあるほうが順序を決定します。

タグの完全セットの例 - この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。X を使用して、@example が、ソースコード内の今回の実行では出力されないタグであることを指定します。@argfile を使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。 行の継続を示す文字は不要です。

   -tag param
   -tag return
   -tag todo:a:"To Do:"
   -tag throws
   -tag see
   -tag example:X

javadoc がドキュメンテーションコメントを解析する際に検出されたタグのうち、標準タグでも -tag や -taglet で渡されるタグでもないものは、未知のタグの見なされます。 この場合、警告がスローされます。

標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。-tag オプションを使用すると、このリストに追加されるタグ、すなわち標準タグの位置がデフォルトの位置から移動します。つまり、標準タグに -tag オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。

競合の回避 - 固有の名前空間を分割するには、パッケージに使用されている com.mycompany.todo のように、ドット (.) 区切りの命名規則を使用します。Sun は、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Sun が提供する同じ名前のタグの動作をオーバーライドします。つまり、ユーザーが @todo という名前のタグまたはタグレットを作成している場合、Sun があとから同じ名前の標準タグを作成しても、そのタグまたはタグレットは元の動作を保持します。

注釈 vs. Javadoc タグ - 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。 それ以外の場合は注釈にすべきです。「Comparing Annotations and Javadoc Tags」を参照してください。

-taglet オプションを使用して、より複雑なブロックタグやカスタムインラインタグを 作成することができます。

-taglet  class
そのタグのドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。クラスの完全指定名を指定してください。このタグレットは、カスタムタグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。外部ドキュメントとサンプルタグレットについては、以下を参照してください。

タグレットは、標準タグまたはインラインタグで便利です。タグレットは任意の数の引数をとることができます。 また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。

タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。

タグレットのパスを指定するには、-tagletpath オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。

    -taglet com.sun.tools.doclets.ToDoTaglet
    -tagletpath /home/taglets 
    -tag return
    -tag param
    -tag todo
    -tag throws
    -tag see

-tag オプションの代わりに -taglet オプションを使用することもできますが、読みやすさを考慮するなら、-tag オプションを使用したほうがよいでしょう。

-tagletpath  tagletpathlist
taglet クラスファイル (.class) の検索パスを指定します。tagletpathlist には、コロン (:) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパスの以下すべてのサブディレクトリを検索します。

-docfilessubdirs 
doc-files ディレクトリの深いコピーを有効にします。つまり、コピー先には、サブディレクトリとすべてのコンテンツがコピーされます。たとえば、doc-files/example/images ディレクトリとその中のファイルがコピーされます。ここでも、サブディレクトリを除外する指定が可能です。

-excludedocfilessubdir  name1:name2...
所定の名前の doc-files サブディレクトリを除外します。これにより、SCCS とその他のソースコード制御サブディレクトリのコピーを防ぎます。

-noqualifier  all  |  packagename1:packagename2:...
出力されるクラス名の先頭のパッケージ名 (パッケージ修飾子) を省略します。-noqualifier の引数として all を指定した場合、すべてのパッケージ修飾子がすべて省略されます。 削除する複数のパッケージ名をコロンで区切って、ワイルドカードとともに指定することもできます。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。

次の例では、すべてのパッケージ修飾子を省略します。

    -noqualifier all
次の例では、パッケージ修飾子 java.lang および java.io を省略します。 
    -noqualifier java.lang:java.io
次の例では、java で始まるパッケージ修飾子と com.sun というサブパッケージ (javax ではない) を省略します。 
    -noqualifier java.*:com.sun.*
パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。 詳細は「名前の表示方法」を参照してください。この規則は、-noqualifier を使用したかどうかにかかわらず有効です。

-notimestamp 
タイムスタンプが抑制されます。 各ページ先頭近くにある、生成された HTML 内の HTML コメントでタイムスタンプが隠されます。Javadoc を 2 つのソースベースで実行し、それらに対して diff を実行するときにこのオプションを使用すると、タイムスタンプによって diff が発生しなくなるので便利です (このオプションを使用しないと、各ページで diff になります)。タイムスタンプには Javadoc のバージョン番号が含まれており、次のようになります。 
     <!-- Generated by javadoc (build 1.5.0-internal) on Tue Jun 22 09:57:24 PDT 2004 -->

-nocomment 
主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言だけを生成します。このオプションにより、元は異なる目的のためだったソースファイルを再利用し、新しいプロジェクトの早い段階でスケルトン HTML ドキュメントを作成できるようになりました。

コマンド行引数ファイル

javadoc のコマンド行を短くしたり簡潔にしたりするために、javadoc コマンドに対する引数 (-J オプションを除く) が入った 1 つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティングシステム上でも、任意の長さの javadoc コマンドを作成できます。

引数ファイルには、javac のオプションとソースファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲みます。

引数ファイル内のファイル名は、現在のディレクトリから見た相対パスになります。引数ファイルの位置から見た相対パスではありません。引数ファイル内のファイル名リストでは、ワイルドカード (*) は使用できません。たとえば、*.java とは指定できません。引数ファイル内の引数で @ 文字を使用して、複数のファイルを再帰的に解釈することはサポートされていません。また、-J オプションもサポートされていません。 このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。

javadoc を実行するときに、各引数ファイルのパスとファイル名の先頭に @ 文字を付けて渡します。javadoc は、@ 文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。

引数ファイルを 1 つ指定する例

argfile という名前の引数ファイルにすべての Javadoc 引数を格納し、次のように使用することができます。

  % javadoc @argfile

この引数ファイルには、次の例で示されている 2 つのファイルの内容を両方とも入れることができます。

引数ファイルを 2 つ指定する例

Javadoc オプション用に 1 つ、ソースファイル名用に 1 つというように、2 つの引数ファイルを作成し、次のようにして使用することができます。なお、このあとのリストでは、行の継続文字を使用していません。

以下の内容を含む options という名前のファイルを作成します。

     -d docs-filelist 
     -use 
     -splitindex
     -windowtitle 'Java 2 Platform v1.3 API Specification'
     -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification'
     -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>'
     -bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.'
     -group "Core Packages" "java.*"
     -overview /java/pubs/ws/1.5/src/share/classes/overview-core.html
     -sourcepath /java/pubs/ws/1.5/src/share/classes

以下の内容を含む packages という名前のファイルを作成します。

     com.mypackage1
     com.mypackage2
     com.mypackage3

そのあと、次のコマンドを使用して javadoc を実行します。

  % javadoc @options @packages

パス付きの引数ファイルの例

引数ファイルには、パスを指定できます。 ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。 つまり、下の例の場合は、path1 や path2 から見た相対パスではありません。

  % javadoc @path1/options @path2/packages

オプションの引数の例

次に、Javadoc オプションに対する引数だけを引数ファイルに格納する例を示します。ここでは、-bottom を例に取り上げます。 そのオプションには、かなり長い引数を指定することがあるからです。まず、このオプションのテキスト引数になる次のような内容を含む、bottom という名前のファイルを作成します。

'<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit a 
bug or feature</a><br><br>Java is a trademark or registered trademark of 
Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun 
Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. 
All Rights Reserved.</font>'

そのあと、次のようにして Javadoc ツールを実行します。

  % javadoc -bottom @bottom @packages

また、引数ファイルの先頭に -bottom オプションを組み込んでおけば、次のようにして実行できます。

  % javadoc @bottom @packages

実行

Javadoc の実行

バージョン番号 - javadoc のバージョン番号を判別するには、javadoc -J-version を使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。-quiet で無効にできます。

公開プログラムインタフェース - Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは com.sun.tools.javadoc.Main にあります (javadoc は再入可能)。詳細は、「標準ドックレット」を参照してください。

ドックレットの実行 - 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、-doclet および -docletpath オプションを使用します。特定のドックレットを実行した完全な例については、MIF Doclet のドキュメントを参照してください。

簡単な例

javadoc は、パッケージ全体に対して実行することも、個々のソースファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。次の例では、ソースファイルは /home/src/java/awt/*.java にあります。生成先ディレクトリは /home/html です。

1 つ以上のパッケージのドキュメント化

パッケージをドキュメント化するには、そのパッケージのソースファイル (*.java) が、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。パッケージ名が複数の識別子で構成されている (java.awt.color のように、各識別子はドットで区切られている) 場合は、後続の各識別子が下位のサブディレクトリに対応していなければなりません (java/awt/color など)。1 つのパッケージのための複数のソースファイルを、異なる場所にある 2 つのディレクトリツリーに分けて格納することも可能です (src1/java/awt/color と src2/java/awt/color など)。 ただし、その場合は、-sourcepath によって、その両方の場所を指定しなければなりません。

javadoc を実行するには、cd コマンドを使ってディレクトリを変更するか、または -sourcepath オプションを使用します。以下の例では、両方の方法について説明します。

結果: 上記のどのケースでも、java.awt と java.awt.event パッケージ内の public および protected クラスとインタフェースについて、HTML 形式のドキュメントが生成され、指定された生成先ディレクトリ (/home/html) に HTML ファイルが保存されます。2 つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラスページという 3 つのフレームを持つことになります。

1 つ以上のクラスのドキュメント化

また、1 つ以上のソースファイル (.java) を渡して、Javadoc ツールを実行することもできます。javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、cd コマンドでディレクトリを変更する方法、もう 1 つは .java ファイルへのパスを完全指定する方法です。相対パスは、現在のディレクトリを起点とします。ソースファイル名を渡すときは、-sourcepath オプションは無視されます。アスタリスク (*) のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。

パッケージとクラスのドキュメント化

パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の 2 つの例を組み合わせた例を示します。-sourcepath は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。

  % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java

この例では、パッケージ java.awt と、クラス Applet について、HTML 形式のドキュメントが生成されます。Javadoc ツールは、Applet のパッケージ名を、Applet.java ソースファイル内のパッケージ宣言 (その宣言がある場合) から判別します。

使用例

Javadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。ここで紹介するのは、Java プラットフォーム API に対して Javadoc ツールを実行するときに使用する実際のコマンドです。Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 個の public および protected クラスについてドキュメントを生成するために、180M バイトのメモリーを使用しました。

同じ例を 2 回掲載します。 最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの javadoc コマンドを実行できます。

コマンド行の例

次のコマンド行の例は 900 文字を超えているため、DOS などのシェルには大きすぎます。この制限を回避するには、コマンド行引数ファイルを使用します。 または、シェルスクリプトを記述します。

% javadoc -sourcepath /java/jdk/src/share/classes            \
    -overview /java/jdk/src/share/classes/overview.html      \
    -d /java/jdk/build/api                                   \
    -use                                                     \
    -splitIndex                                              \
    -windowtitle 'Java 2 Platform 5.0 API Specification'    \
    -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform 5.0 API Specification' \
    -header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>' \
    -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit 
a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, 
Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc. 
901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' \  
    -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
    -group "Extension Packages" "javax.*"                    \
    -J-Xmx180m                                               \  
    @packages

上記のコマンドで、packages は、処理対象のパッケージ名 (java.applet java.lang など) が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー＆ペーストする場合は、-bottom オプションから改行文字を削除してください。さらに、このあとの「注」も参照してください。

Makefile の例

ここでは、GNU Makefile の例を示します。Windows の Makefile の例については、Windows の Makefile の作成方法を参照してください。

javadoc -sourcepath $(SRCDIR)              \   /* Sets path for source files     */
        -overview $(SRCDIR)/overview.html  \   /* Sets file for overview text    */
        -d /java/jdk/build/api             \   /* Sets destination directory     */
        -use                               \   /* Adds "Use" files               */
        -splitIndex                        \   /* Splits index A-Z               */
        -windowtitle $(WINDOWTITLE)        \   /* Adds a window title            */
        -doctitle $(DOCTITLE)              \   /* Adds a doc title               */
        -header $(HEADER)                  \   /* Adds running header text       */
        -bottom $(BOTTOM)                  \   /* Adds text at bottom            */
        -group $(GROUPCORE)                \   /* 1st subhead on overview page   */
        -group $(GROUPEXT)                 \   /* 2nd subhead on overview page   */
        -J-Xmx180m                         \   /* Sets memory to 180MB           */
        java.lang java.lang.reflect        \   /* Sets packages to document      */
        java.util java.io java.net         \
        java.applet
        
WINDOWTITLE = 'Java 2 Platform v1.2 API Specification'
DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification'
HEADER = '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>'
BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit
    a bug or feature</a><br><br>Java is a trademark or registered trademark 
    of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-1999    
    Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.  
    All Rights Reserved.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT  = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.2/src/share/classes'

Makefile の引数は、単一引用符で囲みます。

注

トラブルシューティング

一般的なトラブルシューティング

エラーと警告

エラーおよび警告メッセージには、ファイル名と宣言行 (ドキュメンテーションコメント内の特定の行ではない) の行番号が含まれます。

環境

CLASSPATH
Javadoc がユーザークラスのファイルを探すときに使うパスを指定する環境変数です。この環境変数は、-classpath オプションによってオーバーライドされます。ディレクトリは、次のようにコロンで区切ります。
.:/home/classes:/usr/local/java/classes

関連項目

javadoc は、Sun Microsystems, Inc の商標です (javadoc コマンド自体には商標シンボルは不要)。

Copyright © 2002-2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software